home *** CD-ROM | disk | FTP | other *** search
/ Ian & Stuart's Australian Mac: Not for Sale / Another.not.for.sale (Australia).iso / fade into you / being there / Issues & Ideas / Digital Cash / First Virtual / fv-api.txt < prev    next >
Text File  |  1994-10-15  |  6KB  |  138 lines
  1. Installing and Using the First Virtual API Utilities 
  2. *****************************************************
  3.  
  4. What to Read Here
  5. =================
  6.  
  7. There are three major portions to this document. 
  8.  
  9.  o Obtaining and installing the API Utilities 
  10.  o Using the Shell API 
  11.  o Using the C API 
  12.  
  13. (If you wonder why these are documented together, the Shell API is merely a 
  14. main() for the C API.)
  15.  
  16. Obtaining the software 
  17. =======================
  18.  
  19. If you are reading this document with a World Wide Web browser such as
  20. Lynx or Mosaic, you can probably download the software automatically. The
  21. fv-api files supply a general purpose Application Program Interface for C and
  22. for anything that normally executes commands, such as a UNIX shell or Tcl or
  23. Rexx.
  24.  
  25. To obtain the First Virtual Shell and C API programs, simply click here for a
  26. UNIX "tar" file from the file "pub/code/fv-api/fv-api.tar" on the machine
  27. "ftp.fv.com". If for some reason you cannot use your WWW browser to
  28. download these files directly, feel free to FTP to ftp.fv.com as anonymous.
  29. Then cd /pub/code/fv-api and then get the appropriate file for your
  30. machine. (We plan support for non-Unix machines in the near future.) 
  31.  
  32. Then, read about how to install the software.
  33.  
  34. Installing the software 
  35. ========================
  36.  
  37. You need to install the First Virtual API Utilities to do most kinds
  38. of automatic information sales (i.e., information sales without human
  39. intervention on each sale). These utilities are written in C and
  40. should compile easily on any machine with an ANSI compiler. If you
  41. compiler does not accept function prototypes and other ANSI extensions
  42. to the original K&R C, you can retrieve unproto5.tar from the same
  43. place you got the API Utilities package (or any of many other archive
  44. sites) and follow its instructions to turn your compiler into one that
  45. handles ANSI constructs.
  46.  
  47. Unpack the files into a directory and chdir to that directory. Examine
  48. the Makefile and set any options appropriate to your system. The
  49. commented out default rule for ".c.o" is an example of how to use the
  50. "unproto" program. The Makefile will create one of three final
  51. results: the "fv" program, the "libfv.a" library, and the "fv_ls"
  52. program. Ignore the last for now unless you plan to sell information
  53. with an FTP server. First, type "make fv" to create the "fv" and
  54. "libfv.a" files. Fix any errors that may occur due to programs (like
  55. ranlib) that may be named differently on your system. Then type "fv"
  56. to assure you get a (long) usage summary.
  57.  
  58. Install SGCP as a tcp service at port 440 in your /etc/services file
  59. (if appropriate for your system). Try pinging "card.com" to assure you
  60. have connectivity, then try "fv checkat card.com acct" where "acct" is
  61. your First Virtual Account ID. If all is well, you should see "new" or
  62. "active" as the result. (If you don't have an Account ID already, just
  63. pick something and you'll see "invalid".) A response of "unavailable"
  64. indicates that First Virtual's server could not be contacted or
  65. encountered an error processing the request and probably means the API
  66. Utilities are working but are somehow misconfigured.
  67.  
  68. Read the documentation that comes with the First Virtual API Utilities
  69. now to see how to use the C library and the command-line interface for
  70. various purposes. This document also describes how to create .$
  71. files. These .$ files contain specification lines that configure how
  72. much files associated with them should cost and who should be paid for
  73. them. This is important if you plan to use the API Utilities for an
  74. FTP server or in the context of a WorldWideWeb server with "autosell
  75. or manusell" scripts.
  76.  
  77. Using the Shell API 
  78. ====================
  79.  
  80. There are a multitude of subcommands built into the "fv" command. Most
  81. require some sort of .$ file to be present. Two that don't are "fv checkat"
  82. (which we have already seen) and "fv trstdin". 
  83.  
  84. fv checkat 
  85. +++++++++++
  86.  
  87. fv checkat takes two additional parameters on the command line: the
  88. address of the Internet Information Commerce server to query (card.com)
  89. and an Account ID to check on. The Account ID must be one parameter from
  90. the shell, which means that if you include spaces or special characters, you
  91. should quote or otherwise escape them. fv will print out one of the following: 
  92.  
  93. "unavailable" 
  94.    meaning the server could not be reached or that an internal error
  95.    occured. 
  96. "active" 
  97.    meaning that the account is in good standing. 
  98. "suspended" 
  99.    meaning that the account is in good standing but the owner has not
  100.    answered his email lately. 
  101. "invalid" 
  102.    meaning that either the account does not exist or has been revoked,
  103.    either for nonpayment or for declaring fraud. 
  104.  
  105. These are standard codes returned by the SGCS server, except (obviously) for
  106. "unavailable." 
  107.  
  108. fv trstdin 
  109. +++++++++++
  110.  
  111. This command takes exactly four more command line arguments. A typical
  112. call is fv trstdin card.com transfer@card.com "/usr/lib/sendmail -t" 0
  113. < trfile > respfile Here, card.com specifies the IP address to which a
  114. SGCP connection will be established (on the port specified in
  115. /etc/services), transfer@card.com specifies the email address to which
  116. messages shall be sent if the SGCP protocol is not used, sendmail is
  117. the program into which such an email message should be piped, and 0
  118. indicates the order of preference, with 0 meaning first try SGCP, then
  119. use email if that fails.
  120.  
  121. A full APPLICATION/Green-Commerce transfer-request is read from the
  122. standard input (with either LF or CRLF line terminators) and ends with
  123. either a period alone on a line or the end of file indication.
  124.  
  125. The return from the server is written to standard output (LF
  126. separated, no CRs) terminated by a line with a single period and then
  127. the standard output is closed. The result will always begin with "+OK"
  128. or "-ERR", with a "-ERR" being generated automatically if the server
  129. cannot be contacted and a "+OK" being generated if email was sent.
  130.  
  131. Advanced Shell Interfaces
  132. +++++++++++++++++++++++++
  133.  
  134. Complete documentation on advanced shell interfaces, appropriate for
  135. automatically selling files, is available in documentation that comes
  136. with the programs.
  137.  
  138.